---

10. Compiling and Linking

This chapter discusses how to compile and link a project to produce a final executable file, and how to correct common compiler and linker errors using the Message window. The information in this chapter assumes you have already created a project, added the necessary files, grouped these files, and set the project's options. To learn more about these tasks, refer to other chapters in this book, including "Working with Projects" on page 41, "Working with Files" on page 107, "Editing Source Code" on page 133, and "Configuring IDE Options" on page 249.

You should also be familiar with the columns and pop-up menus in the Project window. To learn more about these features, refer to "Working with Projects" on page 41.

This chapter does not describe in detail the various types of programs the CodeWarrior IDE can create. For that information, please see the Targeting manual appropriate for your platform. A table describing some of these manuals is shown in "Targeting Manuals for various platform targets" on page 28.

The CodeWarrior IDE can only compile and link files belonging to an open project. In other words, you should have a project open before trying to compile any files.

The topics in this chapter are:

• Choosing a Compiler
• Compiling and Linking a Project
• Using Precompiled or Preprocessed Headers
• Preprocessing Source Code
• Disassembling Source Code
• Guided Tour of the Message Window
• Using the Message Window
• Special Library Options (Mac OS)

When you create source-code files, you use a certain programming language, such as C, C++, or Pascal. These languages have naming conventions for the extensions you add to file names. For example, in the C language, a source code file ends with a ".c" extension and a header file ends with a ".h" extension.

This section describes how to correctly associate a file extension with a compiler for a particular language in the CodeWarrior IDE.

The CodeWarrior IDE allows compilation of many different programming languages. The IDE takes a modular approach to compiling code by using various plug-in compilers.

Plug-ins are basically small, loadable code modules that allow the IDE to have many different compilers at its disposal. For example, there are plug-in compilers for C, C++, Pascal, Java, and assembly language.

Plug-in compilers usually have default build-target settings to help the CodeWarrior IDE decide which project files a plug-in handles. During regular compile and link operations, the IDE assigns files to the proper plug-in automatically.

To associate a plug-in compiler with a given file, you must configure the options in the File Mappings settings panel. For a description of how to configure these options to assign a compiler to your source code files, refer to "File Mappings" on page 334.

The CodeWarrior IDE provides many different ways to build a project. When you build a project, you compile it into object code and then link the object code into a final executable file.

All compiling and linking commands are available from the Project Menu. Depending on your project type, some of these commands might be disabled or have different names. For example, you cannot Run a shared library, but you can Make it. Also, a command for compiling or linking might be dimmed because CodeWarrior is busy executing another command, or the project is being debugged.

The CodeWarrior IDE can only compile and link files belonging to an open project. That is, you should have a project open before trying to compile any files.

If you have multiple projects open at the same time, you might want to learn about selecting a default project before compiling and linking. For more information, refer to "Choosing a Default Project" on page 73.

The topics in this section are:

• Compiling Files
• Setting Link Order
• Updating a Project
• Making a Project
• Enabling Debugging
• Running a Project
• Debugging a Project
• Generating a Link Map
• Synchronizing Modification Dates
• Removing Object Code
• Advanced Compile Options

You can instruct CodeWarrior to compile a single file or to compile only certain files in your project. Of course, CodeWarrior can also compile all of the files in your project.

You might want to switch between multiple build targets in a project when compiling files. To learn more, refer to "Setting the Current Build Target" on page 96.

The Compile command in the Project Menu is grayed out in the following situations:

• There is no open project.
• The active editor window does not have a source-code file name extension.
• The active window's source code file is not included in your project.
• (Windows) The binary file, such as the application you created from the project, is running under the debugger.
• (Windows) An application created from the project is running.

A status line displaying the total number of files to be compiled and the number of files being compiled is also provided at the bottom of the Project window.

To compile a single file in your project, select that file in the Project window and choose Compile from the Project Menu.

Alternatively, you can open the file in the CodeWarrior editor, make the editor window the active window, and choose Compile from the Project Menu.

You can compile several files in your project by selecting those files in the Project window and then choosing Compile from the Project Menu. To learn how to select several files in your project, refer to "Selecting Files and Groups" on page 76.

CodeWarrior does not always recognize file changes and might not automatically recompile the file. You can force CodeWarrior to recompile a changed file by "touching" that file. To learn how to touch a file, refer to "Touching and Untouching Files" on page 89.

After touching the file or files that you want to recompile, choose Bring Up To Date or Make from the Project Menu.

You can specify the order in which the IDE compiles files by using the Link Order View of the Project window. By re-arranging the order of the files, you can prevent linkage errors caused by file dependencies. In other words, if file Aleph depends on the completed compilation of file Zeta, you can use change the link order and position file Zeta to compile before file Aleph, thus preventing an error message.

To set the link order in the current project:

1. Click the Link Order tab in the Project window.

The Link Order view appears in the Project window.

2. Sort the files into the desired link order.

Drag and drop each file into the desired build order.

The next time you Bring Up To Date, Make, Run, or Debug the project, the IDE uses the new build order.

See "Link Order View" on page 51 for additional information.

When you have many newly-added, modified, or touched files in your project, you can use the Bring Up To Date command in the Project Menu to compile all of the files.

When using this command, the linker is not invoked, so the compilation does not produce an output binary of your project. The Bring Up To Date command only runs the compiler.

You might want to switch between multiple build targets when updating a project. To learn how to do this, refer to "Setting the Current Build Target" on page 96.

When you are ready to produce a binary file, such as an application, library, or shared library, use the Make command in the Project Menu. This command builds the selected project type by updating the newly-added, modified, and touched files, and then linking the project into a final executable file.

The results of a successful build depend on the selected project type. For example, if the project type is an application, the Make command builds an application and saves that application in the same folder as your project. Table 10.1 lists some sample project types and the resulting files after issuing a Make command. To find a full list of the types of software products you can produce, refer to the Targeting manual for your build target. Refer to Table 1.1 on page 28 to determine which manual applies to various build targets.

Project Type	Build Target	Make Command Creates
Application	Win32	Win32 Application
Library	68K/PowerPC	Mac OS A4 or A5 Library
Dynamic link library	Solaris	Solaris Shared Library (.o)

Once all the modified files and touched files have been compiled successfully, CodeWarrior links all the files in the project to produce your output binary. If the project has already been compiled using Bring Up To Date or another command, then the Make command only links the compiled source code files together.

You might want to switch between multiple build targets in a project when making that project. Refer to "Setting the Current Build Target" on page 96 for more information.

When you choose Enable Debugger command from the Project Menu, the Debug command runs the CodeWarrior debugger in order to debug your project. When you choose Disable Debugger from the Project Menu, the Run command runs your project normally.

To learn how to generate debugging information for all of the files in the project, refer to "Controlling Debugging in a Project" on page 103.

To learn more about running your project, refer to the following section, entitled "Running a Project."

When you choose the Run command from the Project Menu, CodeWarrior compiles and links the project (if necessary), creates a stand-alone application, and then launches that application.

If the current project is not an executable file, the Run command is not available. Non-executable projects include libraries, shared libraries, dynamic linked libraries (DLLs), code resources, and tools.

When compiling and linking is successful, CodeWarrior saves the new application to your hard disk. The new application is named according to options you set in the Target Settings window. If you would like to change these options, refer to "Choosing Target Settings" on page 318.

If the current project is designed to operate on another platform, you must connect your host computer to the target computer or device before choosing the Run command. For additional information, see the appropriate Targeting manual for the target platform.

To debug your project, there are basically two steps you need to do. Of course, you must already have your project compiled and linked with debugging information generated. To learn how to enable debugging for your project, refer to "Enabling Debugging" on page 361.

The second step is for you to launch the debugger with your compiled application as the debug target. You can do this by choosing the Debug command from the Project Menu. If the Debug command is not visible in the menu, your project is not currently configured for debugging. Refer to "Enabling Debugging" on page 361 to learn how to remedy this problem.

After you choose the Debug command, CodeWarrior compiles and links your project, creates a debugging information file, and then opens that information file with the debugger.

If the Debug command is grayed out, make sure to configure the proper options for debugging, as detailed in "Enabling Debugging" on page 361. If the Debug command is still grayed out, you are probably attempting to run a project whose project type cannot be run (such as a shared library or dynamic link library), or the application is already running.

If the current project is designed to operate on another platform, you must connect your host computer to the target computer or device before choosing Run. For additional information, see the appropriate Targeting manual for the target platform.

The CodeWarrior C/C++ compilers let you create a link-map file that contains function and class-section information about the generated object code.

CodeWarrior's Pascal compilers let you create a make-map file that contains a list of dependencies and the compilation order.

The settings to control this option are in the build target's Linker panels. After configuring these panels as desired, you must Make your project. If the compile and link operations are successful, the IDE generates a link-map file, names the file after your project, adds a .MAP extension, and saves the link-map file in your project folder.

To learn more about a build target's Linker panels, see the discussion in the appropriate Targeting manual.

If you want to update the modification dates of all the files stored in the project, choose the Synchronize Modification Dates command from the Project Menu.

To learn more about this topic, see "Synchronizing modification dates" on page 90.

When you compile your project, the CodeWarrior IDE adds the object code from each source file to the project. This binary object code increases the size of the project file. You can choose commands that affect this object code if you want the project file to consume less memory on your hard disk, or if you want to remove all object code and start compilation over again.

In some cases, you might wish to remove all of the object code from the project and restart the compiling and linking process. To remove a project's object code, select the Remove Object Code command from the Project Menu. The dialog box shown in Figure 10.2 appears.

Clicking All Targets removes all object code data for all build targets in the project, and resets the Code and Data size of each file in the Project window to zero. Clicking Current Target removes the object code for the current build target only, and leaves the object code in place for all other build targets. Clicking Cancel aborts the operation, so none of your object code is removed.

To learn how to change the current build target of your project, refer to "Setting the Current Build Target" on page 96.

This command removes all binaries from the project and compacts the project to consume the minimum amount of space on your hard disk. The procedure is similar to that discussed in "Removing Object Code" on page 364, but in addition the project file is compressed.

Compacting the project removes all object code and debugging information stored in the project file, and retains only the information about project-specific option settings and the files that belong to the project.

For more information about this command, refer to "Remove Object Code & Compact" on page 615.

This section describes two options that speed up your project-build times or alert you when a build is completed.

You can start a project compile/link cycle in CodeWarrior, then switch to another application running on your machine. To learn how to receive notification when CodeWarrior completes the build process, refer to "Play sound after `Bring Up To Date' & `Make' (Mac OS)" on page 253.

To learn how to optimize the speed of your builds in CodeWarrior, refer to "Use modification date caching" on page 331.

Source code files in a project typically use many header files (".h" or ".hpp" files). Often, several different source-code files include the same header file, forcing the compiler to (inefficiently) read the same header file many times during the compilation process. Many programming languages support precompiled headers, including C and C++.

To shorten the time spent compiling and recompiling a header file, use the Precompile command in the Project Menu. A precompiled header file takes the compiler significantly less time to process than an ordinary, uncompiled header file.

For instance, a header file that contains the most frequently used headers in your project could be made into one precompiled header file. Instead of having to compile the same thousands of lines of header files for each source file in your project, the compiler only has to load one precompiled header file.

The topics in this section are:

• Creating Precompiled Headers
• Defining Symbols For C/C++
• Defining Symbols For Pascal

To create a precompiled header file, you must first open a project. The settings from this project are used when precompiling. A file to be precompiled does not have to be a header file (".h" or ".hpp"), but it must meet these requirements:

• The file must be a text file. You cannot precompile libraries or other files.
• The file must be saved with a recognized extension, such as ".pch" or ".pch++," at the end of its file name.
• The file does not have to be in a project, although a project must be open to precompile.
• The file must not contain any statements that generate data or code. However, C++ source code can contain inline functions and constant variable declarations (const).
• Precompiled header files for different build targets are not interchangeable. For example, to generate a precompiled header for use with Win32 compilers, you must use a Win32 compiler.
• A source file can include only one precompiled header file using the #include directive.

After you save the text file, the IDE can use that text file to create a precompiled header. You can specify the name of the precompiled header at the time of precompilation. You can also specify the name by including the following line at the beginning of your text file, where name is the name you wish to call the precompiled header:

Append the extension ".mch" to name. This extension is required for precompiled headers.

To precompile a saved text file, choose Precompile from the Project Menu. This command precompiles the text file in the active window, creating a precompiled header file. If compiler errors are detected, a Message window appears.

To learn more about the Message window and correcting compiler errors, consult "Correcting Compiler Errors and Warnings" on page 379.

To learn more about automatic updating of precompiled headers, see the next section, "Automatic updating."

If the source code has been modified, the CodeWarrior IDE automatically updates a precompiled header during a Make or Bring Up To Date operation.

If CodeWarrior encounters a ".pch" or ".pch++" file that was modified since it was last precompiled, the IDE precompiles it again to ensure that the resulting precompiled header is up-to-date.

To create a precompiled header file that is automatically updated, open the project that uses the precompiled header. Then, create a text file that will be used to create the precompiled header.

To read about the requirements for a precompiled header text file, refer to "Creating Precompiled Headers" on page 366.

In the first line of the text file, add the line:

This pragma tells the compiler to create a precompiled header with the file name of name.

Append the extension ".mch" to name. This extension is required for precompiled headers.

When you finish the text file, save it with a valid extension in the same folder as your project.

Save the text file with a ".pch" extension if it will be used to create a precompiled header in either C or C++.

Save the text file with a ".pch" extension if it will be used to create a precompiled header in C. Use the ".pch++" extension if the text file will be used to create a precompiled header in C++.

Next, choose Precompile from the Project Menu.

Now add the text file to the open project using the Add Window command in the Project Menu.

Whenever the precompiled header file is modified, the CodeWarrior project manager automatically updates the header file by precompiling it.

To include the precompiled header in a project source-code file, add this line as the first #include directive in the source-code file:

Alternatively, you can specify a precompiled header as a prefix file, using the settings for your build target. To learn how to do this, refer to the discussion of the C/C++ Language settings panel in the C Compiler Guide.

To automatically update and add predefined symbols and other preprocessor directives, you can create a precompiled header file, add it to your project, and include it in the prefix file specified in the C/C++ Language settings panel.

1. Create a new text file.

Open your project and create a new text file with the New Text File command on the File Menu.

This new text file will contain your preprocessor directives. You will use this file as a precompiled header file that you will add to your project.

2. Open the C/C++ Compiler settings panel.

Choose Target Settings from the Edit Menu. The actual name of the Target Settings command includes the name of the current build target. Select the C/C++ Language settings panel in the Target Settings window.

3. Get the Prefix File name if it exists.

If there is a file name in the Prefix File field, Copy it, then close the Target Settings window.

In the new text file window, paste the file name that you copied from the Prefix File field into an #include directive. Make sure this is the first directive in the text file.

For example, if the prefix file is MyHeaders, then the first directive in the text-file window is:

4. Add the #pragma statement.

Add the #pragma precompile_target statement to the text file. This statement lets you name the precompiled file. For example, to create a file named MyPrecomp, use the following statement:

Append the extension ".mch" to the desired file name. This extension is required for precompiled headers. In this example, "MyPrecomp.mch" is the correct file name.

5. Type in all your own preprocessor directives.

Type in all your own #define, #include, and other preprocessor directives corresponding to the needs of your source code. The text file cannot contain any source code that generates data or executable code. However, C++ source code can contain inline functions and constant variable declarations (const).

6. Save the text file.

Choose Add Window from the Project Menu to add the text file to your project. Save the text file with a valid extension in the same folder as your project.

Save the text file with a ".pch" extension.

Save the text file with a ".pch" extension if it will be used to create a precompiled header in C. Use the ".pch++" extension if the text file will be used to create a precompiled header in C++.

7. Precompile the text file.

Choose Precompile from the Project Menu. The IDE uses the text file to create a precompiled header file.

8. Open the C/C++ Compiler settings panel.

Choose Target Settings from the Edit Menu and select the C/C++ Language settings panel.

9. Set the new Prefix File.

In the Prefix File field, enter the name of your precompiled file, or "MyPrecomp" in this example. Click Save to save your changes.

In this example, you would enter "MyPrecomp.mch" in the Prefix File field.

Whenever CodeWarrior builds your project, the project manager updates your precompiled header and automatically includes it in each source code file.

Although the Pascal preprocessor is not as powerful as the C/C++ preprocessor, you can still create files that can automatically insert your own preprocessor symbols and compiler directives into your project. For more information on the Pascal compiler directives, see the Pascal Language Manual on the CodeWarrior Reference CD.

1. Create a new text file.

Open your project and create a new text file with the New Text File command.

This new text file will contain your compiler directives.

2. Open the Pascal Compiler settings panel.

Choose Target Settings from the Edit Menu. The actual name of the Target Settings command includes the name of the current build target. Select the Pascal Language settings panel in the Target Settings window.

3. Get the Prefix File name if it exists.

If there is a file name in the Prefix File field, Copy it, then close the Target Settings window.

In the new text file window, paste the file name that you copied from the Prefix File field into an include directive, {$I}. Make sure this is the first directive in the file.

For example, if the prefix file is OtherDefs.p, then the first directive in the editor window is:

4. Type in all your own {$SETC}, {$I}, and other preprocessor directives.

The text file cannot contain any source code that generates data or executable code.

5. Save the text file.

Save the file as an ordinary Pascal file in the same folder as your project. For example, save the file with "MyPrecomp.pas" as its name.

6. Precompile the text file.

Choose Precompile from the Project Menu. The IDE uses the text file to create a precompiled header file.

7. Open the Pascal Compiler settings panel.

Choose Target Settings from the Edit Menu, and select the Pascal Language settings panel.

8. Set the new Prefix File.

In the Prefix File field, enter the name of your file, in this example "MyPrecomp", then click Save to save your changes.

Whenever CodeWarrior builds your project, the project manager automatically includes the precompiled header in each source code file.

The preprocessor prepares source code for the compiler. This preprocessor interprets directives beginning with the "#" and "$" symbols (such as #define, $pragma and #ifdef), removes extra spaces and blank lines, and removes comments (such as /**/ and //). You might want to preprocess a file if you want to see what the code looks like just before compilation.

Open a file that you want to preprocess, or select a file in your currently-open Project window. To preprocess a file, select the Preprocess command from the Project Menu. The results of the Preprocess command are stored in a new file. This new file is named after the preprocessed source-code file and begins with the "#" character.

To save the contents of the new window, choose one of the save commands in the File Menu.

If you want to see the code that would be generated for your file, you can disassemble the file. Disassembling is useful if you want to view the machine-level code that is being executed when your source code is executed. In addition, the disassembled code can be a model for writing your own assembly routines. Library files can also be examined using this command.

The Disassemble command in the Project Menu disassembles the compiled source-code file selected in the Project window and displays its assembly-language code in a new window. The title of the new window consists of the name of the source code file with the extension ".dump."

To save the contents of the ".dump" window, choose one of the save commands in the File Menu.If the file being disassembled has not been compiled, choosing the Disassemble command causes the IDE to compile the file before disassembling it.

The Message window, shown in Figure 10.3, is used to display messages about events that have occurred when compiling, linking, or searching files. There are a number of elements in the window that are useful for accomplishing certain tasks, such as navigating to error locations and scrolling to see all messages for a project.

There are some user interface items in the Message window that are not discussed here. To learn about the Marker Pop-Up Menu, Options Pop-Up Menu, VCS Pop-Up Menu, File Path Caption and Line Number Button, refer to "Guided Tour of the Editor Window" on page 133.

The topics in this section include:

• Error Button
• Warning Button
• Project Information Caption
• Extra Information Button
• Stepping Buttons
• Message List Pane
• Source Code Disclosure Triangle
• Source Code Pane
• Pane Resize Bar

The Error Button in the Message window toggles the view of error messages on and off. This is useful if you have changed the view of the window to something else and want to get back to viewing the error messages.

To learn more about seeing error messages in the Message window, refer to "Seeing Errors and Warnings" on page 377.

The Warning Button in the Message window toggles the view of warning messages on and off

To learn more about seeing error messages in the Message window, refer to "Seeing Errors and Warnings" on page 377.

The Project Information Caption gives a short description of the view you are looking at in the Message window. Your project name will appear here.

The Extra Information Button expands a message to show information about the project, target, and file that caused the message.

The Stepping Buttons allow you to step up or down through the messages in the window.

To learn more about stepping through messages in the Message window, refer to "Stepping Through Messages" on page 378.

The Message List Pane displays your messages.

To learn more about seeing messages in the Message window, refer to "Seeing Errors and Warnings" on page 377.

The Source Code Disclosure Triangle allows you to hide the Source Code Pane of the Message window.

The Source Code Pane of the Message window allows you to view the source code at the location referred to by a message. To learn more about the view in this window, refer to "Seeing Errors and Warnings" on page 377.

The Pane Resize Bar allows you to reallocate the amount of space in the Message window given to the Source Code Pane and Message List Pane. By clicking and dragging this bar up or down you will change the amount of space on your computer screen that is allocated to both panes.

While compiling your project, the CodeWarrior IDE may detect a syntax error or other type of compiler error in one of your project's source code files. If this happens, the Message window displays the total number of errors and warnings, and information about each one. See "Guided Tour of the Message Window" on page 373 for information on the interface items in this window.

In this section, you will learn how to interpret, navigate, and use the information that appears in the Message window. The topics in this section include:

• Seeing Errors and Warnings
• Stepping Through Messages
• Correcting Compiler Errors and Warnings
• Correcting Linker Errors
• Correcting Pascal Circular References
• Saving and Printing the Message Window
• Locating Errors in Modified Files

The Message window displays several types of messages:

Select this		To display this
	Errors	Either compiler or linker errors. Both types of errors prevent the compiler and linker from creating a final binary.
	Warnings	Either compiler or linker warnings. Neither type prevents the CodeWarrior IDE from creating a binary. However, they indicate potential problems during run time. You can specify which conditions lead to warning messages or you can upgrade all warnings to errors.
	Notes	All other types of messages issued in the Message window. For example, results of a batch find are notes messages.

To close the Message window, click its close box or select Close in the File Menu while the Message window is the active window. If you close the message window and want to see it again, choose the Errors & Warnings Window command from the Window Menu to reopen it.

To see only error messages in the Message List Pane, click on the Error Button and turn off the Warning Button.

To see only warnings in the Message List Pane, click the Warning Button and turn off the Error Button.

To see both errors and warnings in the Message List Pane, click both buttons. Notes do not appear in the Errors & Warnings window.

You'll also see other types of messages from time to time in a Message window, such as:

• During Add Window or Add Files when a file being added does not reside on an existing access path.
• During linking when a project contains conflicting resources.
• During a Find when the Batch checkbox is selected in the Find dialog box.
• (Mac OS) During a Find Reference when more than one definition for the same function is found (multiple definitions).
• (Mac OS) During a Find Reference on a C++ function that has been overridden, the Message window appears with a warning that there are two or more instances.

When the compiler finds errors during a build, or the CodeWarrior IDE search command finds text you asked it to look for when Using Batch Searches, you will see the message window.

The window is divided into two panes:

• Message List Pane, which lists the messages, or
• Source Code Pane, which displays the source code for the selected message.

To step through the list of messages, click the up or down Stepping Buttons or click the error message you are interested in.

To navigate the source code that is shown in the Source Code Pane for a given message, you use the Interface Pop-Up Menu, Routine Pop-Up Menu, or the Line Number Button. To learn about how to use these navigational features, refer to "Guided Tour of the Editor Window" on page 133.

When an error occurs during compilation, the Message window will show you the error message in the Message List Pane. The location in the source code that the message refers to will be shown in the Source Code Pane. You can navigate to the spot in your source code where the message refers to, and inspect or correct your code.

For a complete list of compiler errors and their possible causes, consult the Error Reference documentation on your CodeWarrior CD.

To correct a compiler error or warning, you must first find the cause. First, make sure that the Source Code Pane of the Message window is visible. If it isn't visible, refer to "Source Code Disclosure Triangle" on page 376 to learn how to make it visible.

To view the statement that the compiler believes has caused the error or warning, select the message in the Message List Pane of the Message window. Notice that the Source Code Pane view now shows the source code that corresponds to the message. A statement arrow points to the line of code that the compiler reports as an error. The statement arrow is shown in Figure 10.4. Using the statement arrow as a guide, you can then edit the erroneous line directly in the Source Code Pane view.

Use the Interface Pop-Up Menu, Routine Pop-Up Menu, or the Line Number Button in the Source Code Pane to navigate your code or open interface files. To learn about how to use these navigational features, refer to "Guided Tour of the Editor Window" on page 133.

To open a source code file that corresponds to a given message, select the message in the Message List Pane and press Enter/Return. You may also double-click the message in the Message List Pane to open the relevant file.

When your project is linked, any errors that may occur can be viewed and corrected.

If the linker encounters any errors while linking your project, the Message window appears indicating these errors. This window can be scrolled through by using the scroll bar or Stepping Buttons.

To learn about how to scroll through messages in the Message window, refer to "Stepping Buttons" on page 375. To learn about changing the view of messages in the Message window, refer to "Seeing Errors and Warnings" on page 377.

Since Linker errors are a result of problems in the object code, the CodeWarrior IDE cannot show their corresponding errors in the project's source code files.

Linker errors are usually the result of one of the following circumstances:

• You have misspelled the name of a library routine. This means that the routine that the Linker is searching for does not exist. Check the name of the routine to make sure it is spelled correctly.
• Your compiled code generates a reference too large to be handled by the selected code model.
• Your project is missing the necessary libraries. Linker error messages of this type occur when the project is missing a library. To find out which libraries or shared libraries should be added to your project, refer to the CodeWarrior Targeting manual appropriate for your platform, as described in Table 1.1 on page 28.

Often a linker error occurs when a library is missing from a project. As a result, one or more functions or identifiers cannot be found and the linker reports a problem. The difficulty you face is trying to figure out which library defines the function or identifier.

To find out which libraries or shared libraries should be added to your project, you can refer to the CodeWarrior Targeting manual appropriate for your target, as described in Table 1.1 on page 28. In addition, you can use the Find Library tool included on the CodeWarrior Tools CD.

Find Library is a set of files with the internal names of functions and global identifiers from many of the libraries included with the CodeWarrior IDE for Mac OS and ANSI Libraries. Use these files as a file set with the CodeWarrior IDE Find dialog box. Search for the missing identifier in these files, and you can quickly find the right library to include in your project.

Here's how to use the Find Library tool.

1. Create a File Set

Use the Find window to create a set that includes all the files in the Find Library folder on your CodeWarrior Tools CD. To learn how to create and use a file set, refer to "Choosing Files to be Searched" on page 187 and "Saving a File Set" on page 191.

2. Set the search parameters to ignore case.

Be sure to select the Ignore Case option when doing your search with the Find window. Some identifiers may be all uppercase or lowercase.

3. Search for the symbol that the linker can't find.

Enter the name of the unlinked symbol, and do a batch search of the Find Library file set. When the search has found a matching identifier, you only need to check the file name of the library to determine the name of the library to include in your CodeWarrior project. There is no path information given in the files, so you'll have to locate the correct library in the appropriate CodeWarrior subdirectory on your hard disk.

For example, if you do a batch search for the identifier num2dec in this file set, you'll get a match in the MathLib file. You now know that if you want to use the num2dec function, you must include the MathLib file in your project.

Some of the 68K and PowerPC shared libraries differ slightly, although the library names are the same. To identify the correct library, we've added the suffix -68K or -PPC as appropriate. For example, DragLib is listed in the Find Library as both DragLib -68k and DragLib -PPC. Ignore the suffix when looking for the library by name, but make sure you include the correct CPU version of the library for your target platform.

The CodeWarrior IDE will report the lines on which matches occur, but you can ignore those line numbers. The line information reported is irrelevant with respect to the actual library, and refers only to the line number in the special naming file.

There are several versions of the ANSI Libraries. They all contain the same identifiers, so only one version is included. You should assume that the appropriate library for your project will contain the same functionality.

The ANSI C++ Library file will be difficult to understand because of name mangling. However, most linker errors will list a function name as well as the identifier. Searching for that function name should give you good results. For example, you might get an error message saying "__aad__9bitstringFRC9bitstring in bitsand.c" is unknown. You could either search for the mangled name or you could search for bitsand to get a match.

The CodeWarrior Pascal compiler's Make and Run commands build your project by examining every Pascal file in your project file. As this examination is performed, a tree of dependencies is built for the interfaces of your units and for their implementations.

A circular reference occurs when a unit declares something that is used in another unit and that same unit declares something used by the former. To break this loop, the Pascal compiler does not allow such things among the interface parts of units, but it is permitted for implementations.

The example in Listing 10.1 is perfectly valid, since both A's and B's interfaces depend on C's, but are independent from one another. Knowing everything that was declared, A's implementation depends on all interfaces, the same is true for B's and C's. For this example, the make utility will ask the compiler to compile Listing 10.1 in the following order:

UNIT A;							UNIT B;								UNIT C;

INTERFACE							INTERFACE								INTERFACE

USES C;							USES C;

TYPE							TYPE								TYPE

	A_type = ...							B_type = ....								C_type = ...

IMPLEMENTATION							IMPLEMENTATION								IMPLEMENTATION

USES B;							USES A;								USES A, B;

....							...								...

1. C's interface is compiled.

2. B's interface is compiled.

3. All of unit A is compiled (unit and implementation),

4. B's implementation is compiled.

5. C's implementation is compiled.

After an interface compilation, the compiler writes a binary symbol table, containing all the declarations of the interface, in a 'sbmf' resource in the project file. This information is read back when the unit's name is encountered in a USES clause for another compilation. A unit is recompiled only when one of the following conditions occur:

• The source was modified,
• The source is currently open and edited, or,
• A unit on which the source depends was recompiled.

To print or save the contents of the Message window, just follow these steps.

1. Make the Message window active.

To accomplish this, either click on the deactivated Message window, or select the Errors & Warnings Window command from the Window Menu.

2. Select the Print command from the File Menu.

If you choose the Print command on the File Menu to print the Message window, the print dialog box appears. Specify printing options and click OK. All the errors, warnings, and messages will be printed.

To learn more about printing, refer to the documentation that came with your printer.

1. Make the Message window active.

To accomplish this, either click on the deactivated Message window, or select the Errors & Warnings Window command from the Window Menu.

2. Select the Save A Copy As command from the File Menu.

The Save A Copy As command will display a standard file dialog box.

3. Specify the name of the file and the location.

A text file will be saved containing all the errors, warnings, and messages that are listed in the message window.

If an error is corrected or the source code is changed, the compiler may not be able to find other errors in the source code file. This may result in an alert telling the user that the position of the error could not be found. When this happens, recompile your project to update the list of errors in the Message window.

There are a few special linker options you can use in your project. These options are only accessible from the Project Inspector window as shown in Figure 10.5, available from the Window Menu. These options are only available for library files in the project, and are disabled for text files in the project.

The topics in this section are:

• Import Weak
• Initialize Before
• Merge Into Output

Import Weak tells the operating system to ignore unresolved symbols at load time. Use this option for features not always installed on all machines (such as QuickDraw GX or QuickTime). For more information on shared libraries, see the Targeting Mac OS manual.

Initialize Before indicates which PEF container (shared library or application) gets initialized first. By default, imported PEF containers are initialized before the PEF containers that import them. Use this option for mutually-dependent PEF containers, to specify which gets initialized first.

Merge Into Output allows you to put a copy of a shared library into your project's output file. For instance, if you have created your own custom shared library, you can merge it into the application's data fork, guaranteeing that the system finds the custom shared library.

This option may be useful for creating fat libraries as well, where you want to include both CFM68K and PowerPC code.